FilCDN M3 Streaming Payments

Overview

This document is a third iteration of proposal for new FilCDN payment architecture, flows and pricing model. Although this is a third iteration it can be viewed as a precursor to the proposal focused on the usage-based payments.

Goal of this document is to outline the before-mentioned payment architecture, payment flows and pricing model.

Glossary

• Payment Rail – The channel through which payments flow from the payer to the payee.

• Payer – Also referred to as the user or client; the entity responsible for making payments to a service provider.

• Payee – Also referred to as the service provider; the entity delivering services in exchange for payments from the payer.

• Service Provider – An entity that offers services such as storage, egress, or compute to clients.

• Storage Provider – A type of service provider specifically offering storage services.

• Account – Tracks funds, lockups, obligations, and related activities associated with an individual owner. Both payers and payees maintain accounts.

• Verifier – A smart contract responsible for verifying proofs or data submitted by a service provider.

• Validator – A smart contract responsible for validating settlement amounts across payment rails.

• Settlement (Rail Settlement) – The process of calculating the payment amount for a defined period, based on pre-determined parameters, and transferring funds from the payer to the payee.

• Operator - Performs operations over payment rails (rate and lockup modification, termination, etc.).

• Service contract – A smart contract responsible for delivering a defined service (e.g., the Filecoin Warm Storage Service). In practice, it often fulfills the dual role of validator and operator.

• Lockup – Funds reserved by the payer to guarantee future obligations. See more on lockups here.

• Streaming Payments – Recurring payments executed over a specified period of time.

• Streaming Lockup – Funds reserved by the payer to ensure successful settlement of streaming payments.

• Fixed Lockup – Funds reserved by the payer to cover one-time payments.

Streaming payments

Streaming payments are a form of recurring payments where compensation is calculated over time. In this model, the settlement amount is determined based on a predefined rate and period during which service has been delivered (duration of providing the service times the rate).

The settlement of streaming payments does not happen on it’s own and payees are expected to settle payment rails regularly.

Current payment architecture

Our current payment architecture is built on two distinct payment rails:

• Payer ↔ Storage Provider: This rail manages payments for cache-miss egress, i.e., data served directly from the storage provider when it is not already cached within the CDN. This ensures that storage providers are fairly compensated for bandwidth consumed when fulfilling requests outside of the CDN cache.

• Payer ↔ FilCDN (service): This rail is responsible for tracking and settling payments related to all CDN egress usage between end users and FilCDN.

The two payment rails are established during the data set setup process, provided that the user opts to enable the CDN service for that data set. At the time of payment rail creation no payment rate is assigned since rates are determined based on amount of data stored. Payment rates for both the storage and CDN services are updated after the total storage volume is known.

Pricing model

Unlike the current pricing model, where users pay a one-time fee for unlimited egress, the new model introduces defined egress limits. Each user is allocated an egress allowance over a specified time period (e.g., up to 1 TiB of egress per month). Users may extend their capacity by either purchasing additional egress (topping up their allowance) or renewing their expired allowance.

Service providers delivering egress will still be rewarded per epoch, regardless of whether the provider has actually served any egress during that epoch, ensuring predictable and continuous compensation.

If a user consumes their entire egress allowance before the service period ends (e.g., 1 TiB of egress used within 3 days), service providers will be able to settle payments until the end of the service period. This gives user the flexibility to top up or renew allowances as needed.

Upgrading current payment architecture

Although current payment architecture effectively uses streaming payments, changes are needed to be done in order to ensure correct payment settlements for the new pricing model and provide additional functionalities like egress top-up.

Changes to rate calculation

Currently, CDN payment rates are calculated based on the total storage size of the data set rather than a flat rate (e.g., $10 for up to 1 TiB / month). To align with the intended pricing model current rate calculation needs to be addressed:

• Update totalBytes value passed to the _calculateCDNRates . Instead of using the actual total bytes stored in the dataset, we should pass the TIB_IN_BYTES constant already defined in the service contract.

• Update CACHE_MISS_PRICE_PER_TIB_PER_MONTH and CDN_PRICE_PER_TIB_PER_MONTH rates so that the split between CDN and SP payment rails reflects the egress usage between the two. This ensures both service providers are properly rewarded based on egress usage (e.g. if only 10% of requests are cache-miss requests SPs should receive only 10% of the rate with CDN receiving 90%). Rates should remain configurable and adjustable as needed.

Off-Chain Tracking of Egress Usage

To complement tracking of usage on per-dataset basis functionality first introduced in PR #197, FilCDN needs to implement calculation of egress allowance. Egress allowance would pose maximum number of egress bytes user (payer) is able to consume via our service.

Egress Allowance per Dataset

In addition to raw usage tracking, we must introduce an egress allowance for each dataset. This allowance should be calculated at the time of dataset creation, during event indexing. The calculation is derived from two sources:

1. Streaming rate – Present under the CDN_PRICE_PER_TIB_PER_MONTH constant inside Filecoin Warm Service Contract.

2. Streaming lockup specified in the payment rail – which determines the guaranteed capacity available for settlement.

Using these values, the system can compute the maximum egress that a dataset is authorized to serve within its payment lockup (i.e. STREAMING_LOCKUP / CDN_PRICE_PER_TIB_PER_MONTH ).

Event-Based Adjustments

To maintain accuracy over time, the worker should listen for additional contract events that affect egress allowance. Key events include:

• RailLockupModified – Used to extend the service duration by increasing lockup duration or to increase the available egress allowance by locking in additional funds in the fixed lockup (top-up).

• RailFinalized or RailTerminated – Used to deactivate service service for the related dataset.

Off-Chain Account Monitoring & Settlement Processes

To strengthen reliability of settlements, new off-chain processes should be deployed to continuously monitor accounts associated with datasets that have CDN enabled.

• Account Monitoring:

  The process should ensure that user funds never fall below the total lockup amount, as this would create a risk of being unable to settle payment rails. If an account balance drops beneath the required threshold, the system should proactively terminate and settle the affected payment rails to prevent any unpaid obligations.

• Periodic Settlement:

  In addition to monitoring, the system should also perform regular settlement of payment rails. This ensures that payments are finalized in a timely manner, reducing the risk of deferred obligations accumulating over long periods.

Verifier contract

The initial version of this contract can remain simple. Future iterations may extend its functionality to record per-dataset egress usage statistics, which could then serve as the basis for implementing the usage-based payment model outlined in the usage-based payments proposal.

Validator contract

To secure operations over the payment rails—such as termination and settlement—a dedicated validator contract is required. This custom validator would serve as the designated validator for all CDN and cache-miss payment rails created going forward.

Similar to the verifier contract, the initial implementation can remain minimal. The first version of settlement validation may simply replicate the approach used in the Filecoin Warm Storage Service. Future iterations, however, would introduce support for adjusting settlement amounts dynamically based on egress usage, as outlined in the usage-based payments proposal.

Service contract

Service contract would provide maximum flexibility for introducing new functionality, such as egress top-up and requester pays for bucket, without adding unnecessary complexity to the Filecoin Warm Storage Service contract. The new contract could serve as both the operator and validator for all FilCDN-related payment rails.

Drawbacks

Future iterations of the validator and verifier contracts will introduce additional complexity, as we will need to operate additional off-chain processes for submission of usage-based reports on-chain. Furthermore, this will require maintaining two sets of usage statistics: one off-chain and another on-chain.

The introduction of this new service contract would slightly impact the user experience. Instead of managing a single operator allowance, users would now need to handle two separate operator allowances, requiring a few additional transactions. In addition, users may need to enable the CDN service independently from dataset creation.

Payment flows

This section outlines the payment flows for additional features needed to provide the best possible user experience. Implementing these features will require either upgrades to the existing Filecoin Warm Storage Service contract or the introduction of a new FilCDN service contract.

Top-up payment flow

This payment flow requires the implementation of a new smart contract method that enables users to purchase additional egress. The function should:

• Validate the inputs provided by the user and confirm that the caller is authorized to perform the operation.

• Calculate the new fixed lockup.

• Attempt to increase the fixed lockup by invoking modifyRailLockup for both the CDN (cache-hit) and the Storage Provider (cache-miss) payment rails.

• Apply the increase according to the configured split (see Changes to rate calculation).

• Off-chain worker observes events emitted by modifyRailLockup and adjust egress allowance for data set.

If either lockup modification fails, the method call must revert.

Extend service duration

Extending service duration follows a flow similar to the top-up mechanism. A new smart contract method should be introduced to allow users to extend the lifetime of their service. The function should:

• Validate the request and authorization.

• Call modifyRailLockup with the updated duration period for both the CDN (cache-hit) and the Storage Provider (cache-miss) payment rail.

• Off-chain worker observes events emitted by modifyRailLockup and adjust egress allowance for data set.

If either rail modification fails, the method call must revert.

Final thoughts

Leveraging the existing streaming payments model provides a minimal and practical foundation to ship early functionality while retaining flexibility for future improvements. Subsequent iterations can then introduce enhancements such as usage-based payments and additional features, including requester pays for settlement.